<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN">
<html>
<head>
<title>DRV_USART_ReadBufferAdd Function</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="generator" content="Doc-O-Matic" />
    <meta http-equiv="Content-Style-Type" content="text/css" />
    <link rel="STYLESHEET" href="default.css" type="text/css" />

<script type="text/javascript" src="scripts.js"></script>
</head>
<body class="Element700" onload="onBodyLoadEx('frames.html', 'topic', '00579.html');" onmousedown="onBodyMouseDown();">

<!-- Begin Popups -->

<!-- End Popups -->

<!-- Begin Page Header -->
<div class="Element710" id="areafixed">
<div class="Element94">
<a href="00007.html" target="topic">Driver Libraries Help</a> &gt; <a href="00165.html" target="topic">USART Driver Library Help</a> &gt; <a href="00166.html" target="topic">Library Interface</a> &gt; c) Data Transfer Functions &gt; <a href="00579.html" target="topic">DRV_USART_ReadBufferAdd Function</a></div>
<div class="Element92">
<table width="100%" cellspacing="0" cellpadding="0">
<tr><td width="25%">
<div class="Element1">
MPLAB Harmony Core Help</div>
</td><td width="25%">
<div class="Element2">
<a href="contents.html" target="tocidx">Contents</a> | <a href="00007.html" target="topic">Home</a></div>
</td><td width="25%">
<div class="Element90">
<a href="00578.html" target="topic">Previous</a> | <a href="00166.html" target="topic">Up</a> | <a href="00584.html" target="topic">Next</a></div>
</td><td width="25%">
<div class="Element96">
<a href="mailto:docerrors@microchip.com&subject=MPLAB Harmony Documentation Feedback (Topic ID: DRV_USART_ReadBufferAdd@DRV_HANDLE@void*@size_t@DRV_USART_BUFFER_HANDLE* const Topic Title: DRV_USART_ReadBufferAdd Function)&body=Thank you for your feedback! Please include a description of your feedback, and indicate whether you are reporting an an error in the documentation or an enhancement.">Documentation Feedback</a><br> <a href="http://support.microchip.com" target="_blank">Microchip Support</a></div>
</td></tr></table><div class="Element5">
DRV_USART_ReadBufferAdd Function</div>
</div>
</div>

<!-- End Page Header -->

<!-- Begin Client Area -->
<div class="Element720" id="areascroll">
<div class="Element721">

<!-- Begin Page Content -->
<a name="PageContent"></a><div class="Element58">
<a name="4465736372697074696F6E"></a><div class="Element11">
<div class="Element10">
<p class="Element10">
This function schedules a non-blocking read operation. The function returns with a valid buffer handle in the bufferHandle argument if the read request was scheduled successfully. The function adds the request to the hardware instance receive queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns <a href="00567.html" target="topic">DRV_USART_BUFFER_HANDLE_INVALID</a> in the bufferHandle argument:</p>
<ul class="Element630">
<li class="Element600">if a buffer could not be allocated to the request because the queue is full</li>
<li class="Element600">if the input buffer handle is NULL</li>
<li class="Element600">if the input buffer pointer is NULL</li>
<li class="Element600">if the buffer size (number of bytes to read) is 0</li>
<li class="Element600">if the driver handle is invalid</li>
</ul><p class="Element10">
&nbsp;</p>
<p class="Element10">
If the requesting client registered an event callback with the driver, the driver will issue a DRV_USART_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_USART_BUFFER_EVENT_ERROR event if the buffer was not processed successfully.</p></div>
</div>
<a name="43"></a><div class="Element99">
C</div>
<div class="Element101"><div class="Element100"><pre class="Element100"><strong><span style="color: #000080">void</span></strong> <strong><span style="color: #000000">DRV_USART_ReadBufferAdd</span></strong>(
    <strong><span style="color: #000080">const</span></strong> <a href="00257.html" target="topic">DRV_HANDLE</a> <strong><span style="color: #000000">handle</span></strong>, 
    <strong><span style="color: #000080">void</span></strong>* <strong><span style="color: #000000">buffer</span></strong>, 
    <strong><span style="color: #000080">const</span></strong> size_t <strong><span style="color: #000000">size</span></strong>, 
    <a href="00566.html" target="topic">DRV_USART_BUFFER_HANDLE</a>* <strong><span style="color: #000080">const</span></strong> <strong><span style="color: #000000">bufferHandle</span></strong>
);</pre></div></div>
<a name="507265636F6E646974696F6E73"></a><div class="Element14">
Preconditions</div>
<div class="Element11">
<div class="Element10">
<p class="Element10">
<a href="00576.html" target="topic">DRV_USART_Open</a> must have been called to obtain a valid opened device handle.</p></div>
</div>
<a name="506172616D6574657273"></a><div class="Element14">
Parameters</div>
<div class="Element11">
<div class="Element10">
<div class="Element312">
<div class="TableDiv">
<table cellspacing="0" class="Table3">
<tr>
<td class="Element300" valign="top" width="35%">
<div class="Element301">
Parameters&nbsp;</div></td><td class="Element304" valign="top" width="65%">
<div class="Element305">
Description&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
handle&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
Handle of the communication channel as returned by the <a href="00576.html" target="topic">DRV_USART_Open</a> function.<br>&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
buffer&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
Buffer where the received data will be stored.<br>&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
size&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
Buffer size in bytes.<br>&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
bufferHandle&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
Pointer to an argument that will contain the return buffer handle.&nbsp;</div></td></tr></table></div></div>
</div>
</div>
<a name="52657475726E73"></a><div class="Element14">
Returns</div>
<div class="Element11">
<div class="Element10">
<p class="Element10">
The buffer handle is returned in the bufferHandle argument. This is <a href="00567.html" target="topic">DRV_USART_BUFFER_HANDLE_INVALID</a> if the request was not successful.</p></div>
</div>
<a name="52656D61726B73"></a><div class="Element14">
Remarks</div>
<div class="Element11">
<div class="Element10">
<p class="Element10">
This function is thread safe in a RTOS application. It can be called from within the USART Driver Buffer Event Handler that is registered by the client. It should not be called in the event handler associated with another USART driver instance. It should not be called directly in an ISR.</p></div>
</div>
<a name="4578616D706C65"></a><div class="Element14">
Example</div>
<div class="Element11">
<div class="Element10">
<div class="Element13"><div class="Element12"><pre class="Element12">
MY_APP_OBJ myAppObj;
uint8_t mybuffer[MY_BUFFER_SIZE];
<a href="00566.html" target="topic">DRV_USART_BUFFER_HANDLE</a> bufferHandle;

<i><span style="color: #008000">// myUSARTHandle is the handle returned</span></i>
<i><span style="color: #008000">// by the DRV_USART_Open function.</span></i>

DRV_USART_ReadBufferAdd(
    myUSARThandle,
    myBuffer,
    MY_BUFFER_SIZE,
    &amp;bufferHandle
);

<strong><span style="color: #000080">if</span></strong>(bufferHandle == <a href="00567.html" target="topic">DRV_USART_BUFFER_HANDLE_INVALID</a>)
{
    <i><span style="color: #008000">// Error handling here</span></i>
}

<i><span style="color: #008000">// Event is received when the buffer is processed.</span></i></pre></div></div>
</div>
</div>
</div>
<!-- End Page Content -->

<!-- Begin Page Footer -->
<div class="Element95">
<a href="00007.html" target="topic">Driver Libraries Help</a> &gt; <a href="00165.html" target="topic">USART Driver Library Help</a> &gt; <a href="00166.html" target="topic">Library Interface</a> &gt; c) Data Transfer Functions &gt; <a href="00579.html" target="topic">DRV_USART_ReadBufferAdd Function</a></div>
<div class="Element93">
<table width="100%" cellspacing="0" cellpadding="0">
<tr><td width="25%">
<div class="Element3">
MPLAB Harmony Core Help</div>
</td><td width="25%">
<div class="Element4">
<a href="contents.html" target="tocidx">Contents</a> | <a href="00007.html" target="topic">Home</a></div>
</td><td width="25%">
<div class="Element91">
<a href="00578.html" target="topic">Previous</a> | <a href="00166.html" target="topic">Up</a> | <a href="00584.html" target="topic">Next</a></div>
</td><td width="25%">
<div class="Element97">
<a href="mailto:docerrors@microchip.com&subject=MPLAB Harmony Documentation Feedback (Topic ID: DRV_USART_ReadBufferAdd@DRV_HANDLE@void*@size_t@DRV_USART_BUFFER_HANDLE* const Topic Title: DRV_USART_ReadBufferAdd Function)&body=Thank you for your feedback! Please include a description of your feedback, and indicate whether you are reporting an an error in the documentation or an enhancement.">Documentation Feedback</a><br> <a href="http://support.microchip.com" target="_blank">Microchip Support</a></div>
</td></tr></table></div>

<!-- End Page Footer -->
</div>
</div>

<!-- End Client Area -->
</body></html>